Skip to main content

Settings Repository

  • Repository for storing information about the installed chart configuration and providing it in aggregated form (for passing it into the chart).
  • Contains business logic with rules for enabling/disabling interdependent menu items.
  • Contains a list of time zones.
  • Items available on the configuration settings screen are configured within the repository.

Repository interface:

/**
* Repository for storing chart settings data.
*
* Default chart settings are set in the implementation of this interface.
*
* Methods are used when interacting with the settings screen elements.
*
* Implementation of this class is mandatory for the library to function. It is passed to [com.devexperts.dxcharts.lib.domain.DxChartsConfig].
*
* Standard implementation is [com.devexperts.dxcharts.lib.data.repo.default_repos.DefaultSettingsRepository].
*/
interface SettingsRepository {
/**
 * Method to set the value of a settings item with Boolean type by passing a value.
 */
fun toggleItem(settingsItem: SettingsScreenItem, value: Boolean)
/**
 * Method to set the value of a settings item with Boolean type by toggling the value.
 */
fun toggleItem(settingsItem: SettingsScreenItem)
/**
 * Method to set the value of a settings item with Color type.
 */
fun changeColor(settingsItem: SettingsScreenItem, value: Color)
/**
 * Method to set the value of a settings item with [HasStringRes] type (dropdown list).
 */
fun selectDropdownItem(settingsItem: SettingsScreenItem, value: HasStringRes)
/**
 * Method to retrieve the complete chart configuration considering all settings.
 */
fun getConfiguration(): ChartConfigurationData
/**
 * Method to get the selected time zone.
 */
fun getSelectedTimezone(): Timezones.TimeZoneItem
/**
 * Method to set the time zone for use in the chart.
 */
fun setSelectedTimezone(timeZoneItem: Timezones.TimeZoneItem)
/**
 * Defines whether the default theme is dark or light based on the provided flag.
 *
 * @param isSystemDefaultThemeIsDark true if the default theme should be dark, false if it should be light.
 */
fun defineSystemSelectedTheme(isSystemDefaultThemeIsDark: Boolean)
/**
 * Method to get the default chart settings set on the first run of the library or when resetting all settings.
 */
fun getDefaultConfiguration(): ChartConfigurationData
/**
 * Method to get the list of available settings items.
 */
fun availableSettingsItems(): List<SettingsScreenItem>
/**
 * Method to get the list of available time zones.
 */
fun availableTimezones(): List<Timezones.TimeZoneItem>
/**
 * Method to get the list of settings items that should be disabled.
 */
fun disabledSettingsItems(): Collection<SettingsScreenItem>
/**
 * Method to notify that the chart aggregation has changed, leading to changes in some settings items.
 */
fun aggregationChanged(aggregation: Aggregation)
/**
 * Method to set the default chart settings.
 */
fun resetDefaultConfig()
}

Classes used in the repository:

  • com.devexperts.dxcharts.lib.domain.SettingsScreenItem - an item in the settings list, listing all available settings options inside:
/**
 * Class for storing data about a settings item.
 *
 * @property submenu The submenu [SettingsSubmenu] where the item is located.
 * @property stringRes String resource with the name of the item for display in the UI.
 * @property type The type of settings item [SettingsItemType].
 */
enum class SettingsScreenItem(
    val submenu: SettingsSubmenu,
    @StringRes val stringRes: Int,
    val type: SettingsItemType,
) {
    CHART_TYPE(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_chart_type,
        type = SettingsItemType.Dropdown,
    ),
    HIGH_AND_LOW(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_high_and_low,
        type = SettingsItemType.Toggle
    ),
    VERTICAL_GRID(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_vertical_grid,
        type = SettingsItemType.Toggle
    ),
    HORIZONTAL_GRID(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_horizontal_grid,
        type = SettingsItemType.Toggle
    ),
    CANDLE_WICKS(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_candle_wicks,
        type = SettingsItemType.Toggle
    ),
    WATERMARK(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_watermark,
        type = SettingsItemType.Toggle
    ),
    TIMEZONE(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_timezones_title,
        type = SettingsItemType.Timezone
    ),
    BULLISH_BODY(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bullish_body,
        type = SettingsItemType.Color
    ),
    BEARISH_BODY(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bearish_body,
        type = SettingsItemType.Color
    ),
    DOJI(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_doji,
        type = SettingsItemType.Color
    ),
    BULLISH_BORDER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bullish_border,
        type = SettingsItemType.Color
    ),
    BEARISH_BORDER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bearish_border,
        type = SettingsItemType.Color
    ),
    UP(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_up,
        type = SettingsItemType.Color
    ),
    DOWN(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_down,
        type = SettingsItemType.Color
    ),
    NONE(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_none,
        type = SettingsItemType.Color
    ),
    AREA(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_area,
        type = SettingsItemType.Color
    ),
    SCATTER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_scatter,
        type = SettingsItemType.Color
    ),
    VOLUME_BULLISH(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_bullish,
        type = SettingsItemType.Color
    ),
    VOLUME_BEARISH(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_bearish,
        type = SettingsItemType.Color
    ),
    VOLUME_DOJI(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_doji,
        type = SettingsItemType.Color
    ),
    BACKGROUND(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_background,
        type = SettingsItemType.Color
    ),
    WATERMARK_COLOR(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_watermark_color,
        type = SettingsItemType.Color
    ),
    GRID(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_grid,
        type = SettingsItemType.Color
    ),
    VALUES_ON_SCALES(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_values_on_scales,
        type = SettingsItemType.Color
    ),
    TRADING_FROM_CHART(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_trading_from_chart,
        type = SettingsItemType.Toggle
    ),
    SHOW_ACTIVE_ORDERS(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_show_active_orders,
        type = SettingsItemType.Toggle
    ),
    SHOW_OPEN_POSITIONS(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_show_open_positions,
        type = SettingsItemType.Toggle
    ),
    AUTO_SCALE_PRICE_AXIS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_auto_scale_price_axis,
        type = SettingsItemType.Toggle
    ),
    FIT_STUDIES(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_studies,
        type = SettingsItemType.Toggle
    ),
    FIT_ORDERS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_orders,
        type = SettingsItemType.Toggle
    ),
    FIT_POSITIONS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_positions,
        type = SettingsItemType.Toggle
    ),
    INVERT_SCALE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_invert_scale,
        type = SettingsItemType.Toggle
    ),
    LOCK_SCALE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_lock_scale,
        type = SettingsItemType.Toggle
    ),
    SCALE_TYPE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_scale_type,
        type = SettingsItemType.Dropdown
    ),
    SESSION_BREAKS(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_session_breaks,
        type = SettingsItemType.Toggle
    ),
    EXTENDED_HOURS(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_extended_hours,
        type = SettingsItemType.Toggle
    ),
    ALIGN_DATA_WITH_SESSION_START(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_align_data_with_session_start,
        type = SettingsItemType.Toggle
    ),
    PRICE_TYPE(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_price_type,
        type = SettingsItemType.Dropdown
    ),
    VOLUME(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_volume,
        type = SettingsItemType.Toggle
    ),
    EVENTS_ON_CHART(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_events_on_chart,
        type = SettingsItemType.Toggle
    ),
    DIVIDENDS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_dividends,
        type = SettingsItemType.Toggle
    ),
    SPLITS_AND_CONSOLIDATIONS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_splits_and_consolidations,
        type = SettingsItemType.Toggle
    ),
    EARNINGS_AND_ESTIMATES(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_earnings_and_estimates,
        type = SettingsItemType.Toggle
    ),
    CONFERENCE_CALLS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_conference_calls,
        type = SettingsItemType.Toggle
    ),
    NEWS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_news,
        type = SettingsItemType.Toggle
    );
    /**
     * Enumeration of available settings submenus.
     * Used for grouping settings items in the UI.
     *
     * @property stringRes String resource with the name of the submenu for display in the UI.
     */
    enum class SettingsSubmenu(@StringRes val stringRes: Int) {
        GENERAL(R.string.dxcharts_settings_submenu_general),
        COLORS(R.string.dxcharts_settings_submenu_colors),
        TRADING(R.string.dxcharts_settings_submenu_trading),
        SCALES(R.string.dxcharts_settings_submenu_scales),
        DATA(R.string.dxcharts_settings_submenu_data),
        EVENTS(R.string.dxcharts_settings_submenu_events),
    }
    /**
     * Enumeration of settings item types.
     * Used to determine the type of settings item in the UI.
     *
     * - [Dropdown] - dropdown list with selectable options
     * - [Color] - color picker
     * - [Toggle] - on/off toggle
     * - [Timezone] - timezone selection
     */
    sealed class SettingsItemType {
        data object Dropdown : SettingsItemType()
        data object Color : SettingsItemType()
        data object Toggle : SettingsItemType()
        data object Timezone : SettingsItemType()
    }
    /**
     * @property dropdownItems Options for selection in dropdown lists within settings items.
     */
    companion object {
        val dropdownItems = mapOf<SettingsScreenItem, List<HasStringRes>>(
            CHART_TYPE to ChartType.entries,
            SCALE_TYPE to ScaleType.entries,
            PRICE_TYPE to PriceType.entries,
            THEME to Theme.entries,
        )
    }

  • com.devexperts.dxcharts.lib.domain.HasStringRes - interface for settings items with a dropdown list displayed on the settings screen:

    • com.devexperts.dxcharts.lib.domain.ChartType
    • com.devexperts.dxcharts.lib.domain.PriceType
    • com.devexperts.dxcharts.lib.domain.ScaleType
/**
 * Interface for data displayed on the settings screen in items with a dropdown list.
 *
 * Classes implementing this interface:
 * - [com.devexperts.dxcharts.lib.domain.ChartType]
 * - [com.devexperts.dxcharts.lib.domain.PriceType]
 * - [com.devexperts.dxcharts.lib.domain.ScaleType]
 */
interface HasStringRes {
    /**
     * Method to get StringRes with the item name
     */
    @StringRes
    fun getStringRes(): Int
}
  • com.devexperts.dxcharts.lib.domain.ChartConfigurationData - data class containing all parameters for chart configuration
/**
 * Data class containing all parameters for chart configuration.
 *
 * Management parameters is happening from the settings screen.
 *
 * The full chart configuration is obtained from [com.devexperts.dxcharts.lib.data.repo.SettingsRepository].
 *
 * @param general General settings
 * @param colors Chart and data colors
 * @param trading Parameters related to trading on the chart
 * @param scales Chart scaling and axis control
 * @param data Data display on the chart
 * @param events Event display on the chart
 * @param unchangeableColors Colors that cannot be changed from the settings screen, set by the developer
 */
data class ChartConfigurationData(
    val general: General,
    val colors: Colors,
    val trading: Trading,
    val scales: Scales,
    val data: Data,
    val events: Events,
    val unchangeableColors: UnchangeableColors
) {
    data class General(
        val chartType: ChartType,
        val highAndLow: Boolean,
        val verticalGrid: Boolean,
        val horizontalGrid: Boolean,
        val candleWicks: Boolean,
        val watermark: Boolean,
        val timezone: Timezones.TimeZoneItem
    )
    data class Colors(
        val bullish: Color,
        val bearish: Color,
        val doji: Color,
        val bullishBorder: Color,
        val bearishBorder: Color,
        val area: Color,
        val scatter: Color,
        val volumeBullish: Color,
        val volumeBearish: Color,
        val volumeDoji: Color,
        val background: Color,
        val watermark: Color,
        val grid: Color,
        val valuesOnScales: Color,
        val highLowValues: Color,
        val paneResizer: Color,
        val crosstool: Color,
        val drawingsText: Color,
    )
    data class Trading(
        val tradingFromChart: Boolean,
        val showActiveOrders: Boolean,
        val showOpenPositions: Boolean
    )
    data class Scales(
        val autoScale: Boolean,
        val fitStudies: Boolean,
        val fitOrders: Boolean,
        val fitPositions: Boolean,
        val invertScale: Boolean,
        val lockScale: Boolean,
        val scaleType: ScaleType
    )
    data class Data(
        val sessionBreaks: Boolean,
        val extendedHours: Boolean,
        val alignDataWithSessionStart: Boolean,
        val priceType: PriceType,
        val volume: Boolean,
    )
    data class Events(
        val eventsOnChart: Boolean,
        val dividends: Boolean,
        val splitsAndConsolidations: Boolean,
        val earningsAndEstimates: Boolean,
        val conferenceCalls: Boolean,
        val news: Boolean
    )
    data class UnchangeableColors(
        val highlights: Highlights
    )
    companion object {
        val EMPTY = ChartConfigurationData(
            general = General(
                chartType = ChartType.CANDLE,
                highAndLow = false,
                verticalGrid = false,
                horizontalGrid = false,
                candleWicks = false,
                watermark = false,
                timezone = Timezones.TimeZoneItem(
                    name = "UTC",
                    fullName = "UTC",
                    offset = 0,
                )
            ),
            colors = Colors(
                bullish = Color(0xFF000000),
                bearish = Color(0xFF000000),
                doji = Color(0xFF000000),
                bullishBorder = Color(0xFF000000),
                bearishBorder = Color(0xFF000000),
                area = Color(0xFF000000),
                scatter = Color(0xFF000000),
                volumeBullish = Color(0xFF000000),
                volumeBearish = Color(0xFF000000),
                volumeDoji = Color(0xFF000000),
                background = Color(0xFF000000),
                watermark = Color(0xFF000000),
                grid = Color(0xFF000000),
                valuesOnScales = Color(0xFF000000),
                highLowValues = Color(0xFF000000),
                paneResizer = Color(0xFF000000),
                crosstool = Color(0xFF000000),
                drawingsText = Color(0xFF000000),
            ),
            trading = Trading(
                tradingFromChart = false,
                showActiveOrders = false,
                showOpenPositions = false,
            ),
            scales = Scales(
                autoScale = false,
                fitStudies = false,
                fitOrders = false,
                fitPositions = false,
                invertScale = false,
                lockScale = false,
                scaleType = ScaleType.REGULAR,
            ),
            data = Data(
                sessionBreaks = false,
                extendedHours = false,
                alignDataWithSessionStart = false,
                priceType = PriceType.LAST,
                volume = false,
            ),
            events = Events(
                eventsOnChart = false,
                dividends = false,
                splitsAndConsolidations = false,
                earningsAndEstimates = false,
                conferenceCalls = false,
                news = false,
            ),
            unchangeableColors = UnchangeableColors(
                highlights = Highlights(
                    afterMarket = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    preMarket = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    regular = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    noTrading = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                )
            )
        )
    }
}
  • com.devexperts.dxcharts.lib.data.model.Timezones.TimeZoneItem - class used to store information about a timezone.
object Timezones {
    /**
     * Constant representing the UTC timezone used in the timezone list.
     */
    val UTC = TimeZoneItem("UTC", "Etc/UTC")
    /**
     * Constant representing the Exchange timezone used in the timezone list.
     */
    val Exchange = TimeZoneItem("Exchange", "Exchange")
    /**
     * Data class used to store information about a timezone.
     *
     * @param name The display name of the timezone in the timezone list (e.g., Buenos Aires).
     * @param fullName The full name of the timezone (e.g., America/Argentina/Buenos_Aires).
     * @param offset The timezone offset relative to UTC in seconds.
     */
    data class TimeZoneItem(
        val name: String,
        val fullName: String,
        val offset: Int? = null
    )
}

Link to the default implementation of the repository - https://stash.in.devexperts.com/projects/DXCHARTS/repos/dxcharts-android/browse/dxcharts_lib/src/main/java/com/devexperts/dxcharts/lib/data/repo/default_repos/DefaultSettingsRepository.kt.

The documentation of the rules for switching items in the settings list is also located there:

  • Events on Chart
  • Trading from Chart
  • Auto scale price axis
  • Extended hours
  • Scale Type

List of the names of time zones used in the library - https://stash.in.devexperts.com/projects/DXCHARTS/repos/dxcharts-android/browse/dxcharts_lib/src/main/java/com/devexperts/dxcharts/lib/data/implementation/DefaultSettingsRepository.kt#730.

Exchanging settings between mobile and web versions​

If you want to exchange settings from mobile version to web version of charts, here you can find the following classes and methods for converting settings between mobile and web versions:

  • com.devexperts.dxcharts.lib.domain.ChartConfigurationDataWeb - data class containing all parameters for chart configuration in the web version
  • ChartConfigurationData.toWeb() - method for converting the mobile version settings to the web version settings
  • ChartConfigurationDataWeb.fromWeb() - method for converting the web version settings to the mobile version settings